/******************************************************
* Copyright (c):   2008, Apache License
* Project:         CS 152 HW 1
* File:            File.h
* Purpose:         Provide an object (struct) for encapsulating FILEs.
* Start date:      September 2nd, 2008
* Programmer:      Michael Gower
* Version:		   1.1
*
******************************************************
*/

#ifndef FILE_H_
#define FILE_H_

#include "../String/String.h"

#include <stdio.h>

/**
 * File, a struct for encapsulating files and file bytestreams.
 */
//TODO keep track of the internal file cursor position better.
typedef struct File_Tag
{
	/**
	 * The filename.
	 */
	pString filename;

	/**
	 * Options (r, rw, a, a+, etc), same as for fopen.
	 */
	pString options; // "r" "rw" "a", etc

	/**
	 * The FILE of the stdlib.
	 */
	FILE* fileHandle;
}File, *pFile, **FileList;

/**
 * Creates a new File object (struct).
 *
 * @param filename The filename of the file to encapsulate.
 * @param fileOptions What to do with the file "r", "rw", "a+", etc.
 *
 * @returns A newly allocated pFile object.
 */
pFile File_new(const pString filename, const pString fileOptions);

/**
 * Creates a new file at filename with specified contents.
 * Overwrites if file exists.
 *
 * @param filename The name of the file.
 * @param contents The contents of the new file, must not be null.
 *
 * @returns The newly created file in a pFile object.
 */
pFile File_Create(const char* filename, const char* contents);

/**
 * Reads an entire file.
 *
 * @param file The File object to be read from
 *
 * @returns The contents of the file (ascii).
 */
pString File_Read(pFile file);

/**
 * Appends to the specified file.
 *
 * @param file The file to append to.
 * @param toAppend The string to append.
 *
 * @returns 1 on success, 0 on failure.
 */
int File_Append(pFile file, pString toAppend);

/**
 * Empties the specified file.
 *
 * @param file The file to erase.
 *
 * @returns 1 if success, 0 on fail.
 */
int File_Empty(pFile file);

/**
 * Returns the size of the file in bytes.
 *
 * @param file The File object to operate on.
 *
 * @returns the size in bytes.
 */
int File_getSize(pFile file);

/**
 * Closes the file.
 *
 * @param file The File object.
 *
 * @returns 1 on success, 0 on failure.
 */
int File_Close(pFile file);

/**
 * Deletes the file entirely.
 *
 * @param file The File object holding the file to delete.
 *
 * @returns 1 on success, 0 on failure.
 */
int File_Delete(pFile file);

#endif /* FILE_H_ */
